home *** CD-ROM | disk | FTP | other *** search
/ Games of Daze / Infomagic - Games of Daze (Summer 1995) (Disc 1 of 2).iso / x2ftp / msdos / libs / knowhow4 / know_how.doc < prev    next >
Text File  |  1994-05-30  |  14KB  |  335 lines
  1.                             KNOW-HOW 4.x
  2.                      GUI LIBRARY WITH EXTENTIONS
  3.                             SOURCE CODES
  4.                         BORLAND C++ 3.X, DOS
  5. (C) Stepan S. Vartanov, 1992, 93, 94
  6.  
  7. INTRODUCTION.
  8.      KNOW-HOW is a library for BC 3.x. It includes:
  9.      KNOW-HOW.Interface with  windows,  icons,  menus,  PCX  support,
  10. screen output  of LJ  (SFP) fonts   and so on. EGA/VGA 16 colors. KHI
  11. also provides  support scripts:  user could record keyboard pressings
  12. to file,  play them  or link  them with  any "hot key". Window system
  13. supports multiple  overlapped windows,  and could  simulate switching
  14. between tasks.
  15.      KNOW-HOW.BGI. Abstract drawing functions for vector primitives
  16. with zooming, rotation, mirror and scrolling, and concrete represen-
  17. tation - BGI child class. 
  18.      KNOW-HOW.DRAW.  PaintBrush-like   PCX-editor   (source   codes),
  19. designed as part of KH hierarchy. Could be included to user's program
  20. without changing any code at all.
  21.      KNOW-HOW.PRINT. Keep  on disk  RGB screen of any size, scroll it
  22. in clip  region on  screen, with  or without  deformation, print this
  23. screen or  part of  it on printers of different types with or without
  24. deformation.
  25.      KNOW-HOW.GRAF.  Plot   on  screen   graphics  using  "LINES  and
  26. MARKERS", "BAR",  "3D BAR"  or "STACKED  BAR" presentation. Manual or
  27. automatic mark axes.
  28.      KNOW-HOW.SLANG.  Basic   -  like   language.  It's   child  (C++
  29. terminology) could  have functions  to axess  facilities of  concrete
  30. package. Usage: any spreadsheets, calculators, and creating languages
  31. for integrated packages.
  32.      KNOW-HOW.SLANG.DRAW. SLANG-based  drawind tool,  vector graphics
  33. editor. The new language derived from SLANG have additional functions
  34. for graphic  output. KNW-HOW  could be  connected with  this tool  to
  35. produce interactive painting program.
  36.      KNOW-HOW.DATASHELL. Extention  for BORLAND  PARADOX ENGINE 3.01.
  37. View, edit or ask tables, Multytable QBE and so on.
  38.      KNOW-HOW.DEBUG. Creates  protocol of  memory operations (new and
  39. delete) of program, even if it handles computer. Very powerful tool.
  40.  
  41. HOW TO STUDY KNOW-HOW.
  42.  
  43.      Library  complectation  includes  all  source  codes.  They  are
  44. commented enought  to giude  themself. In  addition almost  every CPP
  45. file contains  remarked main() function which illustrate usage of the
  46. concrete class.  Example projects  are ready  to  compile.  They  are
  47. designed to  explain the  KNOW-HOW ideas,  and could  be used as real
  48. commercial programs prototypes. Few aspects which require the special
  49. discussion are documented here.
  50.  
  51. Class Visible.
  52.      All classes of KNOW-HOW which are able to interact with user are
  53. derived from this class. The base class in KH hierarchy. Please read
  54. attentively all the comments to file.
  55.  
  56. FILE VISIBLE.H
  57. /* Base class for any classes which may be put to interface container
  58. (ObjectKit, ApplicationKit ...).
  59.      "ret" is the flag, it determines the behaviour of object after
  60. it lost the control (See below).
  61.      exe() is the main function of object, it executes every time
  62. when we choice object. WINDOWS synonym is WndProc() function.
  63.  
  64.      "event" structure contains information about type of event
  65. happened, coordinates of mouse cursor and so on. Menu and some other
  66. objects may replace events, for example, mouse pressing on "exit"
  67. button may be replaced with keyboard "EVENT_ESC".
  68.      "action_type" contains type of action (user-defined function) of
  69. the last used object, or 0.
  70.      "global_num" contains number of menu item, global_i[0] contains
  71. action_type value. To read more about reserved variables of KNOW-HOW,
  72. see file GLOBAL.H.
  73. */
  74.  
  75. #ifndef __VISIBLE_H_
  76. #define __VISIBLE_H_
  77.  
  78. #include "addevent.h"    // Event handler, the most complete version.
  79. #include "action.h"      // Reserved messages of KNOW-HOW
  80. #include "global.h"      // Temporary storage structures.
  81.  
  82. enum where_mouse { MOUSE_OUT, MOUSE_IN };
  83.  
  84. enum ret_flags   { RET_OK = 1, RET_CANCEL = 2, RET_MOUSE = 4,
  85.              RET_ANY = 7, RET_TRANSFER = 8, RET_REMOVE = 16,
  86.              RET_SHOW = 32, RET_STACKED = 64 };
  87. /* RET_  message transfer.  This flags  control is  it  necessary  to
  88. remove object  from screen when input focus is lost. RET_ANY is their
  89. combination.
  90.      For example,  we work  with file list, and click 22-thmenu item.
  91. If bit  RET_TRANSFER == 0, control will be passed to object pointTo +
  92. 22 -  1 (PointTo  is the number of next object, and callForm - number
  93. of previous).  If RET_TRANSFER  == 1,  object pass  control to object
  94. with number (in upper container) pointTo.
  95. */
  96.  
  97. class Visible
  98.      {
  99.      protected:
  100.           int object_number;  // Number of base window.
  101.      int ret;                 // Group of flags.
  102.      int pointTo;   // Object to pass control if OK EVENT handled.
  103.      int callFrom;  // Object to pass control if CANCEL EVENT.
  104.      int action_type;    // What to do after OK EVENT.
  105.      int once;           // Is the object active?
  106.  
  107.      public:
  108.           Visible()
  109.                { once = ret = pointTo = callFrom = action_type =
  110.                     object_number = 0; }
  111.  
  112.      virtual ~Visible() { }
  113.      int active() { return once; }  // Is it active
  114.      void set_active(int a) { once = a; }
  115.      int get_object_number() { return object_number; }
  116.      void set_object_number(int n) { object_number = n; }
  117.      virtual void repose(rect ) {}
  118. /* For every object we could write the analog of constructor. We call
  119. it after resizing of base window in container. This function will
  120. recalculate coordinates of all elements of class.
  121. */
  122.      int isRet(int what) { return ret & what; }
  123. // For example: isRet(RET_OK | RET_CANCEL)
  124.      int isPoint() { return pointTo; }
  125.      int isAct() { return action_type; }   // ACTION.H and user's
  126.      int isCall() { return callFrom; }
  127.  
  128.      void assign(int pnt, int act_type)
  129. // Links objects. Assign action to object.
  130.           {
  131.           pointTo = pnt;
  132.           action_type = act_type;
  133.           }
  134.  
  135.      void set_call(int call) { callFrom = call; }
  136.      void set_point(int p) { pointTo = p; }
  137.  
  138.      void set_ret(int r) { ret = r; }
  139. // F.e.: set_ret(RET_OK | RET_CANCEL)
  140.  
  141.      virtual void exe(int act = 0) = 0;
  142. // Main function - user interface.
  143.      virtual void show() = 0;    // Show the object
  144.      virtual void hide() {}
  145.      where_mouse mouse_in(loc l)
  146. // Is the mouse inside this object or outside. contains() and
  147. // other KNOW-HOW geometry see GEOM.H and GRAPHPP.H
  148.      { return (where_mouse)(bound().contains(l)); }
  149.      virtual rect bound() = 0;  // Rectangle including this object
  150.      virtual void touch(int i = 0) {}
  151. // Fill global_... structures reserved by KNOW-HOW with
  152. // class-specific data
  153.      };
  154.  
  155. #endif __VISIBLE_H_
  156.  
  157.  
  158. SIMPLIFIED CLASS INTERFACE.
  159.  
  160.      Here is  the brief  discussion of  how  KNOW-HOW  operates  with
  161. windows and menus.
  162.      Usually, object-oriented  event driven  systems used complicated
  163. event handlers. Single action, as "Close The Window" generate cascade
  164. of child messages. The main task of SCI is to use single message with
  165. the same  effect. Object's reaction to some events is determined, and
  166. SCI guaranties  that class  will never  meet with  another events and
  167. messages (so called "soldier - serguant principle").
  168.  
  169. FLOW CONTROL IN KNOW-HOW.
  170.  
  171.      Lets  discuss  event  processing  (event  handling  -  see  next
  172. chapter). We  shell call  "container" the  class, which  keep list of
  173. pointers to  other objects,  including  containers.  KNOW-HOW  use  3
  174. levels of containers:
  175.      OBJECT (menu with mouse buttons)
  176.      APPLICATION (example - Borland IDE)
  177.      PROGRAM (example two Paintbrushes, running under Windows).
  178.      SCI provide  3 ways  to leave  object: with  OK message  (RETURN
  179. pressed on  menu item),  with CANCEL  message (ESC  pressed), or when
  180. mouse button  is pressed  outside of  object. To  determine  object's
  181. behaviour SCI use 3 bits of variable "ret":
  182. enum { RET_OK = 1, RET_CANCEL = 2, RET_MOUSE = 4 ...
  183.      This flags  control is it necessary to remove object from screen
  184. when input focus is lost. RET_ANY is their combination.
  185.      Lets, for  example, working  with file  list we  click 22-thmenu
  186. item. If  bit RET_TRANSFER  == 0,  control will  be passed  to object
  187. pointTo +  22 - 1 (PointTo is the number of next object, and callForm
  188. - number  of previous).  If RET_TRANSFER == 1, object pass control to
  189. object with number (in upper container) pointTo.
  190.      Another example.  We are working with menu NEW, OPEN, SAVE. Last
  191. two items  should call  object "file  menu". The following code shows
  192. the solution:
  193.  
  194. Header:
  195. enum { AC_USER = 101, ... AC_NEW, AC_OPEN, AC_SAVE... };
  196. extern int file;
  197. enum { NEW, OPEN, SAVE };
  198.  
  199. CPP file:
  200. int file = NEW;
  201. void application(int action_number)
  202. // User functions. Every program should contain it's version.
  203.     {
  204.     ...
  205.     switch(action_number)
  206.         {
  207.         ...
  208.         case AC_NEW: new_file(); return 1;
  209. /* new_file()  is user-defined  function,  return  value:  1  -  pass
  210. control to  prev. object  in menu cascade, 0 - keep control, 2 - call
  211. next object.
  212. */
  213.         case AC_OPEN: file = OPEN; return 2;
  214.         case AC_SAVE: file = SAVE, return 2;
  215.         ....
  216.         case AC_FILE:
  217.             switch(file)
  218.                 {
  219.                 case OPEN: open_file(); break;
  220.                 case SAVE: save_file(); break;
  221.                 }
  222.             return 1;
  223. ....
  224.      NEW choice  will call  new_file() function, and then remove menu
  225. from screen.  OPEN or  SAVE will pass control to file menu, and after
  226. its execution open_file() or save_file() is called.
  227.      The next  problem is:  how do we know that next object is namely
  228. file menu?  Filling the  Application  container  we  should  use  the
  229. following code:
  230.  
  231. ApplicatioKit* kit = new...   // Constructor
  232. kit->add(menu);               // NEW, OPEN, SAVE menu
  233. ...
  234. kit->add(file_sys);           // file menu
  235. ...
  236. menu->set_ret(...RET_TRANSFER...);
  237. assign(file_sys, menu, AC_NEW);
  238. assign(..., file_sys, AC_FILE);
  239.  
  240.      All items of menu points to the same object (RET_TRANSFER is 1),
  241. user function  of 1-st  position of  the "menu" is AC_NEW (AC_NEW + 1
  242. for second  position and  so on),  and user  function of  file_sys is
  243. AC_FILE.
  244.  
  245.      RET_REMOVE flag means that object will be removed from container
  246. when ALT/F3 pressed (usefull in multywindw systems).
  247.      RET_SHOW forses  the system  to redraw  all window every time it
  248. becomes active.
  249.      RET_STACKED determines  type of  the window. If it is 0, that is
  250. popup window, and if it is 1, window could be invoked in the multiple
  251. overlapped windows system. Usually, popup windows are used in cascade
  252. menus or dialogs.
  253.  
  254. USER-DEFINED FUNCTIONS.
  255.  
  256.      KNOW-HOW reserves  functions (messages)  with numbers  0 -  100.
  257. User could  to register  his own  messages with numbers 101 - ... For
  258. example:
  259. #define AC_COLOR 101 // Registration
  260.  
  261. application(int act)
  262.      {
  263.      switch(act)
  264.           {
  265.           ...
  266.           case AC_COLOR: setcolor(RED); return 0;
  267.           ...
  268.  
  269.      Object  keep   the  number  of  its  function  in  data  element
  270. "action_type".  If   object  may  call  different  functions  (menu),
  271. action_type is the FIRST function in list of possible choices.
  272.      Reserved actions see the file ACTION.H
  273.  
  274.      Any event  was happened  (RETURN pressing,  f.e.). Object  which
  275. have had  focus of input get this message and, depending of the value
  276. of its  "ret" class  data member hide (or not) itself. Then if it was
  277. "OK"-type event,  application(action_type) is  called.  There  are  3
  278. possible scenaries  after execution  of this function: go to previous
  279. object, keep  control in  current object  or go  to the  next object.
  280. Numbers of objects (numbers of pointers to them in the list of upper-
  281. level container)  are in  callFrom and  pointTo class  variables. The
  282. concrete scenary  depends of  the number  (0, 1, 2) returned by user-
  283. defined function.
  284.  
  285. EVENTS.
  286.  
  287.      Event  handler  (ACTION.H,  EVENT.H,  MOUSE.H  and  so  on,  see
  288. EVENT.PRJ). Files  are good  documented, so only brief description is
  289. given.
  290.      There are  4 types  of events:  NOEVENT, KEYEVENT, SHIFTKEYEVENT
  291. (CTRL, ALT,  SHIFT and Lock... keys involved), MOUSEEVENT. Delpressed
  292. is not eq. to 0 if DEL key is holded.
  293.      The  most   important  mouse   events:  MOUSELEFT,   MOUSERIGHT,
  294. MOUSECENTER, MOUSELEFT2 ...
  295.      To get  information use getevent(), readevent() and eventavail()
  296. functions.  Parameters   of  this  functions  are  OR-combination  of
  297. constants mentioned above: KEYEVENT, SHIFTKEYEVENT and MOUSEEVENT.
  298.  
  299. INTERFACE COLORS.
  300.  
  301.      File COLORS.SET contains few standart color sets in format:
  302. COLOR comment
  303. COLOR comment
  304. COLOR comment
  305. ....
  306. @ end of set No 1
  307. COLOR comment
  308. COLOR comment
  309. COLOR comment
  310. ...
  311.  
  312.      Colors could be changed using load_set_color(int COLORSETNUM)
  313. function.
  314.      Objects of KNOW-HOW could also use different fill patterns (in
  315. PATTERNS.CPP):
  316. char pattern[][8] =
  317.     { { 255, 255, 255, 255, 255, 255, 255, 255 },
  318.     ...........................................
  319.  
  320. GEOMETRY.
  321.  
  322.      GEOM.H file defines geom. objects in C++ manner: loc(x, y)
  323. defines pint, rect(x1, y1, x2, y2) - rectangle and so on.
  324.      GRAPHPP.H file overload BGI functions using GEOM.H structures.
  325.  
  326. SCRIPTS AND MACROSES.
  327.  
  328.      Event manager could use events, which was previuosly recorded to
  329. file. get_event() funtion (file ADEVENT) uses global flag
  330. SCRIPT_MODE. If it is equial to RECORD, all user input is duplicated
  331. to file scriptFileName (GLOBAL.H). If it is PLAY, event source is
  332. file, not keyboard. See examples of scripts and macroses
  333. (MACROS.MAC).
  334.  
  335.